Configuring HashiCorp Vault

To set up Vault using a ProtectServer 3 HSM, complete the steps described in this section.

Enabling the PKCS#11 Seal

The PKCS#11 seal configures Vault to use a ProtectServer 3 HSM with PKCS#11 as the seal wrapping mechanism.

To enable the PKCS#11 Seal

1. Create a configuration file for Vault named "config.json" and specify the seal, storage, and listener stanzas.

   # PKCS #11 seal
   seal "PKCS #11" {
   lib = "<path to cryptoki library>"
   slot = "<slot number>"
   pin = "<partition password>"
   default_key_label = "HashiCorp_root"
   key_label = "HashiCorp_root_new"
   default_hmac_key_label = "HashiCorp_hmac_root"
   generate_key = "true"
   }
   storage "file" {
   path = "/tmp/vault"
   }
   
   # Addresses and ports on which Vault will respond to requests
   listener "tcp" {
   address     = "127.0.0.1:8200"
   tls_disable = "true"
   }
   ui = true
   

   • lib is the path to the PKCS#11 library shared object file.

   • slot is the HSM partition slot number.

   • pin is the HSM partition password.

   • hmac_key_label is the label of the key to use for HMACing.

   • Generate key instructs Vault to generate a key if no existing key with the label specified by key label can be found at Vault initialization time.

   Note

   Alternatively, the HSM seal can be activated by providing the following environment variables:

   • VAULT_HSM_LIB

   • VAULT_HSM_SLOT

   • VAULT_HSM_PIN

   • VAULT_HSM_KEY_LABEL

   • VAULT_HSM_HMAC_KEY_LABEL

   • VAULT_HSM_GENERATE_KEY

   Although the configuration file allows you to pass in VAULT_HSM_PIN as part of the seal's parameters, it is strongly recommended to set this value via environment variables.

Configuring Entropy Augmentation

Vault Enterprise version 1.3 introduced the entropy augmentation function to leverage an HSM for augmenting system entropy via the PKCS#11 protocol.

To configure entropy augmentation, define the entropy stanza in config.json.

# Entropy 
entropy "seal" {
mode = "augmentation"
}

Starting Vault

After enabling the PKCS#11 seal and configuring entropy augmentation, start the Vault server using config.json.

# ./vault server -config config.json

Initializing Vault

You must initialize Vault before accessing it.

When Vault is initialized while using an HSM, recovery keys are returned to the operator instead of unseal keys. Some Vault operations, such as root token generation, will require these recovery keys.

To initialize Vault

1. Launch a new terminal session and run the following command:

   # export VAULT_ADDR='http://127.0.0.1:8200'
   

   Note

   Vault must continue running in the first terminal while you complete the remaining steps of this integration.

2. Check the status of Vault.

   # ./vault status
   

   

3. Initialize Vault.

   # ./vault operator init -recovery-shares=1 -recovery-threshold=1
   

   The preceding command will generate a recovery key and initial root token. Copy these keys and secure them.

   

   Note the following logs in the first terminal where the Vault server is running:

   2022-01-28T14:25:37.597-0600 [INFO]  core: loaded wrapping token key
   2022-01-28T14:25:37.597-0600 [INFO]  core: successfully setup plugin catalog: plugin-directory=
   2022-01-28T14:25:37.597-0600 [INFO]  core: no mounts; adding default mount table
   2022-01-28T14:25:37.598-0600 [INFO]  core: successfully mounted backend: type=cubbyhole path=cubbyhole/
   2022-01-28T14:25:37.598-0600 [INFO]  core: successfully mounted backend: type=system path=sys/
   2022-01-28T14:25:37.599-0600 [INFO]  core: successfully mounted backend: type=identity path=identity/
   2022-01-28T14:25:37.601-0600 [INFO]  core: successfully enabled credential backend: type=token path=token/
   2022-01-28T14:25:37.601-0600 [INFO]  core: restoring leases
   2022-01-28T14:25:37.604-0600 [INFO]  rollback: starting rollback manager
   2022-01-28T14:25:37.604-0600 [INFO]  identity: entities restored
   2022-01-28T14:25:37.604-0600 [INFO]  identity: groups restored
   2022-01-28T14:25:37.604-0600 [INFO]  mfa: configurations restored
   2022-01-28T14:25:37.604-0600 [INFO]  core: stopping replication
   2022-01-28T14:25:37.604-0600 [INFO]  core: closed sync connection
   2022-01-28T14:25:37.604-0600 [INFO]  core: replication stopped
   2022-01-28T14:25:37.604-0600 [INFO]  core: setting up replication
   2022-01-28T14:25:37.604-0600 [INFO]  core: replicated cluster information not found or disabled, not activating client
   2022-01-28T14:25:37.604-0600 [INFO]  core: replication setup finished
   2022-01-28T14:25:37.604-0600 [INFO]  expiration: lease restore complete
   2022-01-28T14:25:37.612-0600 [WARN]  core: post-unseal upgrade seal keys failed: error="no recovery key found"
   2022-01-28T14:25:37.612-0600 [INFO]  core: post-unseal setup complete
   2022-01-28T14:25:37.634-0600 [INFO]  core: root token generated
   2022-01-28T14:25:37.634-0600 [INFO]  core: pre-seal teardown starting
   2022-01-28T14:25:37.634-0600 [INFO]  core: stopping replication
   2022-01-28T14:25:37.634-0600 [INFO]  core: closed sync connection
   2022-01-28T14:25:37.634-0600 [INFO]  core: replication stopped
   2022-01-28T14:25:37.634-0600 [INFO]  rollback: stopping rollback manager
   2022-01-28T14:25:37.634-0600 [INFO]  core: pre-seal teardown complete
   2022-01-28T14:25:37.634-0600 [INFO]  core: stored unseal keys supported, attempting fetch
   2022-01-28T14:25:37.648-0600 [INFO]  core.cluster-listener: starting listener: listener_address=127.0.0.1:8201
   2022-01-28T14:25:37.649-0600 [INFO]  core.cluster-listener: serving cluster requests: cluster_listen_address=127.0.0.1:8201
   2022-01-28T14:25:37.649-0600 [INFO]  core: post-unseal setup starting
   2022-01-28T14:25:37.664-0600 [INFO]  core: loaded wrapping token key
   2022-01-28T14:25:37.664-0600 [INFO]  core: successfully setup plugin catalog: plugin-directory=
   2022-01-28T14:25:37.664-0600 [INFO]  core: successfully mounted backend: type=system path=sys/
   2022-01-28T14:25:37.664-0600 [INFO]  core: successfully mounted backend: type=identity path=identity/
   2022-01-28T14:25:37.664-0600 [INFO]  core: successfully mounted backend: type=cubbyhole path=cubbyhole/
   2022-01-28T14:25:37.666-0600 [INFO]  core: successfully enabled credential backend: type=token path=token/
   2022-01-28T14:25:37.666-0600 [INFO]  core: restoring leases
   2022-01-28T14:25:37.666-0600 [INFO]  rollback: starting rollback manager
   2022-01-28T14:25:37.666-0600 [INFO]  identity: entities restored
   2022-01-28T14:25:37.666-0600 [INFO]  identity: groups restored
   2022-01-28T14:25:37.666-0600 [INFO]  mfa: configurations restored
   2022-01-28T14:25:37.666-0600 [INFO]  core: stopping replication
   2022-01-28T14:25:37.666-0600 [INFO]  core: closed sync connection
   2022-01-28T14:25:37.666-0600 [INFO]  core: replication stopped
   2022-01-28T14:25:37.666-0600 [INFO]  core: setting up replication
   2022-01-28T14:25:37.666-0600 [INFO]  core: replicated cluster information not found or disabled, not activating client
   2022-01-28T14:25:37.666-0600 [INFO]  core: replication setup finished
   2022-01-28T14:25:37.666-0600 [INFO]  expiration: lease restore complete
   2022-01-28T14:25:37.674-0600 [INFO]  core: post-unseal setup complete
   2022-01-28T14:25:37.674-0600 [INFO]  core: vault is unsealed
   2022-01-28T14:25:37.674-0600 [INFO]  core: unsealed with stored keys: stored_keys_used=1
   

4. Verify the keys generated on the slot.

   ctkmu list –s<slot> -u<userpin>

   

Logging In to Vault

You must log on to Vault to begin configuring and managing the secrets engine.

To log on to the Vault

1. Log on to Vault.

   # ./vault login <VAULT-TOKEN>
   

   <VAULT-TOKEN> is the initial root token generated during Vault initialization.

   

2. Verify that the Vault server is initialized and auto-unsealed.

   

3. If the UI has been enabled in config.json, access the Vault UI at http://127.0.0.1:8200/ui

   

   Input the VAULT TOKEN in the Token field to log on.

Using the Secrets Engine

Secrets engines are components that store, generate, or encrypt data. The KV secrets engine is used to store arbitrary secrets within the configured physical storage for Vault. Versioning can be enabled and a configurable number of versions for each key will be stored.

To use the secrets engine

1. View secrets.

   # ./vault secrets list
   

   

2. Enable the KV secrets engine.

   # ./vault secrets enable -version=1 kv
   Success! Enabled the kv secrets engine at: kv/
   

3. Write arbitrary secret data.

   # ./vault kv put kv/my-secret my-value=s3cr3t
   Success! Data written to: kv/my-secret
   

4. Display the secret value.

   # ./vault kv get kv/my-secret`
   
   ====== Data ======
   Key         Value
   ---         -----
   my-value    s3cr3t
   

Enabling Entropy Augmentation

To leverage the external entropy source, set the external_entropy_access parameter to true while enabling a secrets engine or auth method.

To enable the external entropy source on a transit secrets engine

1. Enable transit secrets engine with the external entropy source.

   # ./vault secrets enable -external-entropy-access transit
   Success! Enabled the transit secrets engine at: transit/
   

2. List the enabled secrets engine with the -detailed flag.

   

   External Entropy Access is set to true for transit.

3. Use the transit secrets engine to encrypt sensitive data that leverages the HSM as its external entropy source, and create a new encryption key named "orders".

   # ./vault write -f transit/keys/orders
   Success! Data written to: transit/keys/orders
   

4. Send a base64-encoded string to be encrypted by Vault.

   # ./vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111")
   Key           Value
   ---           -----
   ciphertext    vault:v1:ZXKU9Yc8+BefMCkPJVUksh5y0NlTymeToyTKl7NzdE5I4CpRtcjjPnUsvVmwPpQ/
   

5. Verify that the ciphertext can be decrypted.

   # ./vault write transit/decrypt/orders \ciphertext="vault:v1:ZXKU9Yc8+BefMCkPJVUksh5y0NlTymeToyTKl7NzdE5I4CpRtcjjPnUsvVmwPpQ/"
   Key          Value
   ---          -----
   plaintext    NDExMSAxMTExIDExMTEgMTExMQo=
   

6. Decode to get the original plaintext string.

   # base64 --decode <<< NDExMSAxMTExIDExMTEgMTExMQo=
   4111 1111 1111 1111
   

This completes the integration of HashiCorp Vault with a ProtectServer 3 HSM.